Repository navigation
Conversation
viktorce
force-pushed
the
fix/terminal-clear-live-screen
branch
from
November 19, 2026 23:43
d1ca3fe to
0dbc1e6
Compare
viktorce
force-pushed
the
fix/terminal-clear-live-screen
branch
from
November 20, 2026 00:12
0dbc1e6 to
80b2519
Compare
…eaves stray characters on screen A control sequence can reach a client in two pieces of output. When a `cleared` event arrived between them, the client appended the erase text ESC[H ESC[2J ESC[3J to the terminal's output. The ESC that starts it made the emulator abandon the sequence it was reading and draw the rest as text. A cursor-position query, ESC[6n, split around a clear put a stray "n" on the screen and was never answered. A colour change, ESC[31m, put a stray "m" there and lost the colour. clearOutput now sends the start of the unfinished sequence again after the erase, so the rest completes it on the cleared screen. A new contracts helper, unfinishedTerminalSequence, finds that start from the last ESC with the shared parser model. It leaves out C0 controls that arrived inside an escape or CSI sequence, because the emulator already ran them. With no sequence open a clear sends the same bytes as before. The text fallback still starts empty after a clear. A string that a program never ends, such as an OSC with no terminator, now stays open across a clear, where the erase text used to end it. When later output trims the buffer inside such a string, the text fallback hides the rest of it, as it already did with no clear. Three cases get worse. A clear stores an open string again, so the next output can evict older output, including output that set modes. On a server that still drops queued output at a clear, the reopened sequence takes its ending from whatever comes next, so ESC[6 with a dropped "n" and then "hello" shows "ello". An OSC query gets one extra reply for each clear that lands after a complete query inside the string.
viktorce
force-pushed
the
fix/terminal-clear-live-screen
branch
from
November 20, 2026 00:37
80b2519 to
3a84fa7
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #38.
Clearing a terminal while a control sequence had half arrived made every attached client draw the other half as text.
A control sequence can reach a client in two pieces of output. On a
clearedevent,clearOutputinpackages/client-runtime/src/state/terminalOutput.tsappends the erase textESC[H ESC[2J ESC[3Jto the terminal's output. TheESCthat starts the erase text makes the emulator abandon the sequence it was reading. The emulator then draws the rest of that sequence as text.clearOutputnow appends the start of the unfinished sequence again, right after the erase text. The emulator reads the start a second time on the erased screen, and the rest of the sequence completes it. With no sequence open, a clear appends the same bytes as before.A new helper,
unfinishedTerminalSequenceinpackages/contracts/src/terminal.ts, finds that start with the model of Ghostty's parser states that the client already uses to trim output. Web, desktop and mobile all handleclearedthroughclearOutput.The branch sits on
e37e45fd5b. Forkmainhas moved to57db750b8fsince, with no change to the files this fix touches or reads.What changes on screen
Each case prints
beforeand the first part of a sequence, getscleared, then prints the rest andafter.ESCandBELstand for those control characters, and the spaces next to them are for reading.ESC[6n, the cursor-position query, split afterESC[6nafter, and no replyafter, and the replyESC[1;1RESC[31m, a colour change, split afterESC[31mafterin the default colourafterin redESC[2;3H, a cursor move, split afterESC[2;3Hafteron row 1afterat row 2, column 3ESC]0;title BEL, a window title, split aftertitleafterafterESC]8;;http://example.com ESC\, a hyperlink, split afterexample.comafterafterIn every row the screen now has the text, colours and cursor position of an emulator that starts empty and gets the whole sequence and
afterin one piece. The rows come from a throwaway probe against the web client's real Ghostty core. The committed Ghostty test covers rows 1 and 4.Before you merge: output that
maindrops at a clearmainstill drops queued output at a clear, which is #9 and which #30 fixes. When the rest of an open sequence was in that dropped output, the sequence this PR reopens takes its ending from whatever comes next.busy ESC[6, thenndropped, thenhellohelloello, because thehendsESC[6hbusy ESC[?1049, then the rest dropped, thenhellohelloelloon the alternate screen, because thehendsESC[?1049hbusy ESC]0;ti, then the rest of the title dropped, thenhellohelloIt needs the paused delivery behind #9, which about 100,000 clears in the running app did not reach. The bug this PR fixes needs no paused delivery.
The client cannot tell that the server dropped output, so it cannot avoid this. The owner decided that this PR targets
mainand does not wait for #30.Why the start is sent again, and the erase is not held back
A sequence takes effect when its last character arrives. For a split sequence that is after the clear, so the result should be the erased screen with the sequence applied to it. Erase, then
ESC[2;3H, putsafterat row 2, column 3. Holding the erase back until the sequence ends would run the move first and the erase second. The erase homes the cursor, andafterwould land on row 1. #34 makes the same choice for the saved history.The helper starts at the last
ESCin the retained output, because anESCstarts a new sequence from every parser state. It returns nothing when the output ends outside a sequence, or no longer holds thatESC.It leaves out C0 controls, such as LF and TAB, that arrived inside an escape or CSI sequence. Ghostty runs those when they arrive, and sending them again would run them twice. Inside a string they are string content or ignored, and the helper keeps them.
How this relates to #33 and #34
It is the same split, seen from two sides. #33 is about the server's saved history, which a client gets when it attaches, reconnects or reopens the terminal. #34 fixes that and is stacked on #30. This PR is about the screen of a client that stays attached.
Neither fix needs the other's code. This PR changes
packages/client-runtime,packages/contractsand a test inapps/web. #34 changes onlyapps/server/src/terminal/Manager.tsand its test file.They do belong together. I compared the live screen with a replay of the saved history in nine split cases. Either fix alone makes them disagree in 8 of the 9. With both, all nine agree and none shows stray text.
How the comparison was made
mainmainb5c9783bacmainmainb5c9783bacThe one case that always agrees has no open sequence.
The nine cases are a query, a colour change, a cursor move, a bare
ESC, a title string ended byBEL, a title string split inside itsESC \end, a hyperlink, a string that never ends, and a clear with no open sequence. A throwaway server test printed the saved history for each case, one37e45fd5band on #34's head. A throwaway Ghostty test then compared whole screen snapshots of the live client with an emulator reset and fed each history. Neither is committed.On
mainwithmain, seven cases show the same stray text on both sides. In the eighth, the string that never ends, both showplain text, which the string should have swallowed.The client side ran on this PR's first head,
d1ca3fe7e5. None of the nine cases has a control inside an escape or CSI sequence, so the final code sends the same bytes in all nine.A string that never ends
A program can start an OSC, DCS, PM or APC string and never end it. The emulator then swallows all later output. #37 covers what that does to the server.
Before this PR, a clear ended such a string on the client as a side effect of the erase text's
ESC, and the stuck emulator drew again. Nothing tested it.The decision: on the client, a clear leaves an open string open, at any size the client still retains. The client sends the string's start again like any other unfinished sequence, so after the erase the emulator is back inside the string until it ends. With
before ESC]0;stuck, a clear, thenplain text, the screen showedplain textbefore and shows nothing now.Why:
The mobile text fallback follows the same rule. Right after a clear it starts empty, as before. When later output trims the buffer inside the reopened string, the fallback hides the rest of that string, as it already does with no clear. Before, the clear had ended the string and that text showed. With a 16-byte buffer,
ESC]0;, a clear, thenabcdefghijklmnopshowed the 16 letters before and shows nothing now. With no clear it shows nothing on both.What still ends the string is what ends it with no clear: an
ESC, a CAN or a SUB from the program, aBELfor an OSC, a new snapshot when the client attaches again, or restarting the terminal. In a DCS, PM or APC string, a character whose UTF-8 bytes include one from 0x80 to 0x9F ends it, or starts another sequence. Once an open string has grown past what the client keeps, the last 512 KiB of output by default, itsESCis gone, and a clear ends the string as it does today.What gets worse
The clear key no longer gets a frozen screen drawing again. A terminal stuck inside a string that never ends stays stuck after a clear, where before the erase text ended the string.
A large open string is stored again at each clear. A probe printed an unended 400 KiB string and cleared five times with no output between. Retained output went from 409,610 bytes to 2,457,685, against a budget of 524,288, where before it went to 409,665. The next output trims back to the budget and evicts everything older, including output that set modes. With no output between, growth stops only at the 1,024-chunk limit, near 16 MB. With
ESC[?1hprinted first, that limit started evicting at clear 39, and from clear 40 retained output stayed at 16,122,456 bytes with the mode-setting output gone. The replay then no longer extends the one before, so an older mobile binary recreates its emulator, without the mode. Before, 60 clears ended at 410,269 bytes. Each clear also feeds the whole open string through the emulator of every attached client.I added no size limit. #37 asks for one only for the text the server holds, and nothing tracks this cost on the client yet.
An OSC query is answered once more at each clear. Ghostty acts on an OSC string when the string ends, however it ends. That includes the erase text cutting it short, which is not new. A CAN or a SUB in place of the
ESCbehaves the same, so the erase cannot end a string quietly. With the start sent again, Ghostty acts on the string again when it really ends. For a string that sets something, such as a title, the whole string is applied last. What the cut-short string did before it is not undone, and that part is not new. For a query, the program gets one extra reply for each clear that lands after a complete query inside the string:ESC]11;? BEL, split right before theBELESC]11;? BEL, two clears right before theBELESC]11;? BEL, split afterESC]11;?drawn as textESC]4;1;?;2;? BEL, split after1;?;2;?drawn as textThe reply goes to the pty. If the program that asked has stopped reading, whatever reads next gets it, usually the shell's line editor.
I kept the extra reply because the ways around it cost more. The client would have to know which OSC commands reply, or hold the erase back until a string ends, which a string that never ends would block for good.
These observations come from the web wasm build, which shares Android's Ghostty revision. A CSI sequence acts only at its final character, so
ESC[6cut short by the erase drew no reply. DCS and APC drew no reply, cut short or whole.The rest is inferred, not observed. iOS runs full Ghostty, which may answer DCS and APC queries, so an extra reply is possible there too. A string that acts once each time it ends, such as an OSC 9 notification, would act once more for each clear.
Mobile
Only the mobile app has a clear key. It sends
terminal.clear, and the server sendsclearedto every client attached to that terminal. Web sends Ctrl+L to the shell instead, see #9. So a web or desktop client hits this only while a mobile client clears the same terminal.What I ran: the session test, which pins what each mobile path below gets, the Ghostty test, and mobile's own 41 terminal tests, which pass unchanged. The Ghostty test runs Android's parser source on a different target, since Android pins the web wasm's Ghostty revision,
3ff6d08fad56f2d6b81420a27bdc56ee707b453e, and its two patches leave the parser alone.What I did not run:
GhosttyKit.xcframeworkfrom a fork, with no slice that runs on a Mac. The shared model decides which bytes are sent again, not the emulator.terminal.clearas a plain RPC with no mobile client. The Ghostty test already runs the real reducer, reader, writer and core, so the pass would add only the transport, which this PR does not change.To check by hand on a device, run
printf 'before\033[31'; sleep 10; printf 'mafter\n'in the terminal and tap the clear key during the sleep. Before this PR the screen showsmafterin the default colour. With it the screen should showafterin red.The three ways output reaches a mobile screen
Mobile handles
clearedthrough the sameapplyTerminalAttachStreamEventandclearOutputas web.readTerminalOutputUpdatethroughcreateTerminalOutputWriterand feed the bytes to native Ghostty. iOS callsghostty_surface_feed_data. Android uses libghostty-vt.terminalOutputReplayasinitialBuffer. They recreate their emulator unless the new buffer extends the last one. The session test uses a full buffer and a string with a two-byte character, so it fails if a clear trims the buffer.terminalOutputText, and draws escape sequences as plain text. Right after a clear it starts empty and shows the rest of a split sequence as text,nafter, as before. Trimming inside a reopened string is the one case that differs, see "A string that never ends".The web wasm is built from the revision in
native/libghostty-vt/VERSION, andruntimeAbi.test.tschecks it against that file. The Android build script pins the revision by itself and does not read that file.Tests
packages/contracts/src/terminal.test.ts, "unfinishedTerminalSequence", one table of eight rows for the helper.packages/client-runtime/src/state/terminalSession.test.ts, "sends the start of an unfinished control sequence again after the erase". The title string arrives in two outputs and fills a 16-byte buffer. The test checks the bytes a live reader gets, the replay for older binaries, extended and not trimmed, and the empty fallback text.apps/web/src/terminal/ghostty/core.test.ts, "completes a control sequence that a clear splits", two rows. Each compares the whole screen snapshot and the replies with an emulator that gets the sequence in one piece. The rows take different paths in Ghostty, since the erase makes it act on an unfinished OSC and not on an unfinished CSI.All three fail without the fix, and each of twelve single-change mutations fails at least one.
vp run check:changedand the terminal suites pass: 12 tests inpackages/contracts, 31 inpackages/client-runtime, 95 inapps/webacross the Ghostty core, surface, ABI and drawer files, and 41 inapps/mobile.Test transcripts, on base and on this branch
The issue's test, added verbatim before any change, failed on
e37e45fd5bwithexpected 'nafter' to be 'after'andexpected 'mafter' to be 'after'. The committed tests replace it.Base below means
terminalOutput.tsandpackages/contracts/src/terminal.tsfrome37e45fd5b, with this branch's tests. The helper does not exist there, so its table fails withunfinishedTerminalSequence is not a function.Mutations: twelve single changes, each fails a test
ESC,indexOfforlastIndexOfcurrent.chunks.at(-1)?.data ?? ""ESC,if (escape < 0) return "";unit <= 0x20forunit < 0x20Upstream search
I searched pingdotgg/t3code again on 2026-11-19, issues and pull requests in every state, by keyword and by the files changed. I found no issue or PR for this bug. Upstream
mainatcb391b5b57has the sameterminalOutput.tsand parser model as this branch's base.Related upstream work, by number only: PR 36380, merged 2026-11-13, introduced the erase text. PR 36368, merged the same day, added the parser model this fix uses. Open PR 34786 adds an unrelated function to the same file and leaves
clearOutputalone. Open PRs 25192 and 22092 change what the server'scleardoes to queued events, which is #9 and #31 here.Implemented by Claude Fable 5.2 and Claude Opus 5.5 in Claude Code (T3 Code). Reviewed by Claude Opus 5.5, Claude Fable 5.2 and GPT-6.1 Sol.